Helping us to help you
I want us to be able to provide meaningful and timely help with your projects when other avenues have failed to unstick things.
There are a few things you can do to make it easier for us to help you.
Try other avenues first!
- Try debugging your code with print statements or logging (see this chapter of the DES book for an intro!)
- Make sure you’ve saved any changes!
- Close your terminal and rerun (or, if using a notebook, hit ‘clear all outputs’ and ‘restart’)
- Take a general look on Google
- Take a look at StackOverflow
- Ask the community via your project channel
- Try using an AI tool (Perplexity and ChatGPT are both good options), but take everything it says with a pinch of salt…
- make sure you go through code it provides carefully so you understand it, and consider writing (formal or informal) tests to verify it works properly
Make your code available…
If all else fails - I really am happy to help (and have taken a look at various issues for people this year)!
It helps if you can give me as much information as possible about
- what you’ve already tried
- what seems to be going wrong
- what you’re trying to achieve, and why
Having your code available on GitHub is the easiest way for us to troubleshoot issues.
If you cannot provide it on GitHub, sending code files to us on Slack is acceptable, but please attach it as a file to a Slack message rather than copying and pasting.
… and runnable!
Please either provide
- an environment.yml or requirements.txt (if you have made your own environment from scratch)
- or details of which of the HSMA environments you have used, and any packages you’ve added into those environments
If you are using branches, please make it clear which branch we need to be looking at!
What if I’m not allowed to share?
We might still be able to help!
Can you give us the gist of your problem? Like before, this might involve talking about
- what you’ve already tried
- what seems to be going wrong
- what you’re trying to achieve, and why
You could also look into
- whether you’re able to share part or all of the code without data
- providing simple fake data (which you could even make in something like Excel)
- this is also a great option for wider sharing and reproducibility of your code
Making your code readable
Understanding someone else’s code can be tricky - and time-consuming - at the best of times.
The following will really help us!
- Comments!
- Extensive comments are our friends at this stage. Why have you taken a particular approach? What is a given function doing?
- Too many comments > too few
- Good variable and function names increase readability
- e.g. rather than ‘x, y, z’ or ‘input_1, input_2’, make your variables more descriptive, like ‘total_referrals’, ‘number_of_nurses’
- Commenting out (or removing) unused code
- The shortcut of highlighting code and pressing
CTRL + / can make it easier to get temporarily comment out bits of code
- Adhering to PEP8 guidance on line length makes a big difference too
Making your code super readable with docstrings
One of the best ways to make your code even easier for us to work with is to use docstrings.
Docstrings are like a super-comment that makes it easier to understand your functions, classes, and methods - wherever you are accessing them in the code.
When you start using a function from a package and it pops up with a load of extra useful details, that’s its docstring you are seeing.
Working asynchronously
A ‘quick meeting’ can often take a lot more time than you’d think!
(and in all honesty, unless it’s something like a typo, I’m unlikely to be able to resolve it within a call - though if you’d strongly prefer this, I can work with it)
However, I can often squeeze in some time looking at problems and then send you details of
- what I fixed
- how I went about working out what to do!
GitHub Issues
GitHub issues are a great built-in (and free) way of tracking aspects of your project.
They are almost a built in to-do list to help you track what needs to happen - and what’s already happened.
They can be particularly useful for collaborative projects, but can also be very handy for solo projects.
What can we use issues for?
The great thing about your repo… is that it’s your repo!
Established projects may have more rules about what can be an issue and how it’s formatted, but you can set the rules on your project.
So you could use issues for
- Features you want to add
- Data you need to obtain
- Documentation you need to write
- Minor (and major!) bugs you need to fix
Examples of projects using issues - vidigi
In the vidigi issues, I’m primarily talking to myself and using it as a big to-do list.
Examples of projects using issues
In another project, we have used it for three of us to be able to communicate asynchronously about the project
Communication via Issues - a sneak peak
Including to summon me! (more on this later)
![]()
![]()
The Issues Tab
In your repositories, whether they are public or private, you should see an ‘Issues’ tab.
Our First Issue
When we first load this up, there’s nothing here… so let’s change that!
We’ll click the ‘New Issue’ button
Populating our first issue
The minimum we need to provide is a title (though it’s a good idea to put in some description too)
Viewing our first issue
This will take us to a view where we can add comments to the issue.
- We can edit the title with the ‘edit’ button
- We can edit the description with the three dots
- We can close the issue when we’ve resolved it
Viewing our issue list
Heading back to our ‘issues’ page we can now see this in our list of issues.
Labels
Labels allow us to
- group issues
- make it easy to quickly identify what an issue is
Github provides us with a selection of predefined labels that we can choose from.
Adding our own labels
By clicking on ‘edit labels’ we are taken to a page where we can create any label we fancy
![]()
![]()
Filtering by Labels
On our issues page, we can then click on the ‘labels’ dropdown to only find certain kinds of issue.
![]()
Note - the filter won’t happen until you click elsewhere on the screen (outside of the label popup)
Mentioning issues elsewhere
It can be really helpful to mention issues on other issues, or in pull requests!
Typing a # symbol brings up a list of recent issues, and by starting to type you can filter it down.
![]()
![]()
How mentioned issues display
Mentioned issues will turn into a link when you save the description or comment
![]()
And they’ll show up in the linked issues and pull requests too
![]()
Tagging People in issues
If you mention someone by their GitHub username - prefacing it with an @ symbol - then they will get a notification.
![]()
On a public repo - or one where you’ve added me as a collaborator - you could summon me like that!
Closing Issues
When you are done with an issue, we can write a comment (optional, but recommended!) and close it down.
If we want to, we can mention the ID of the pull request that closes this issue, or even the exact commit hash!
Fancy issue closing
In pull requests, if we mention an issue by ID with the # notation, it will
- expand the issue ID into the issue name
- automatically close the issue when the pull request is merged in if you use certain keywords like ‘resolves’
Milestones - another approach
In another project, we’ve tied it in more detail to due dates and goals.
Creating a milestone
From the issue page, click ‘milestones’.
![]()
Then ‘new milestone’
![]()
Populating milestone details
From this, you can then enter a title of your choice, an optional due date, and any details to flesh out things like key goals or requirements.
Adding issues to a milestone via the milestones page
Now, when we click on the milestone header, we are given the option to add any issue to our new milestone.
Projects
Projects are an optional extra that you can use to enhance your use of issues.
We can access them from the ‘Projects’ header.
Creating a new project
We’ll click ‘new project’
Choosing aa project template
We’ll be provided with a list of possible project layouts.
My favourite is Kanban - but feel free to experiment!
Setting the project name
Give your project a name.
Our project
Initially we’re presented with a list of empty columns.
![]()
We then click on ‘add item’
Adding issues to columns
This brings up a search bar
Clicking on the plus gives us some more options.
![]()
If we click ‘add items from repository’ we can access our current repo’s issues - or issues from other repos!
![]()
Managing your proejct
Once this is done, we have an issue in the column.
![]()
We can move this around as we progress. Moving it to done automatically closes it!
![]()
Managing columns
Clicking on the three dots allows us to change the default limit for issues per column (0 = no limit)
![]()
We can also add, delete and reorder columns (by clicking and dragging them).
![]()